home *** CD-ROM | disk | FTP | other *** search
/ Alles Voor Internet / Tout Pour Internet / alles voor internet.iso / MacInternet™ / Telnet / NCSA / tn3270 2.4d7 source / tn3270 / api.h < prev    next >
Text File  |  1992-01-26  |  20KB  |  514 lines
  1. /* tn3270 API Interface */
  2.  
  3. /* This file defines the content of messages sent to or from the tn3270
  4.    API.  These messages are sent using either the SPPC driver or the
  5.    PPC Toolbox in System 7 and later.  Due to limitations of the SPPC
  6.    driver, the longest message cannot exceed 128 bytes.               */
  7.  
  8. /* Note: all characters strings are C strings (null delimited).        */
  9.  
  10. /* message type values */
  11. #define ErrorResponseType        4001
  12. #define GetIdRequestType        2
  13. #define GetIdResponseType        4002
  14. #define GetCapRequestType        3
  15. #define GetCapResponseType        4003
  16. #define GetVersRequestType        4
  17. #define GetVersResponseType        4004
  18. #define OpenRequestType            5
  19. #define OpenResponseType        4005
  20. #define GetConnStatusType        6
  21. #define GetConnResponseType        4006
  22. #define GetCharRequestType        7
  23. #define GetCharResponseType        4007
  24. #define CloseRequestType        8
  25. #define CloseResponseType        4008
  26. #define CloseNotifyRequestType    9
  27. #define CloseNotifyResponseType    4009
  28. #define CloseEventResponseType    4010
  29. #define GetBuffersRequestType    11
  30. #define GetBuffersResponseType    4011
  31. #define WriteNotifyRequestType    12
  32. #define WriteNotifyResponseType    4012
  33. #define WriteEventResponseType    4013
  34. #define SendDataRequestType        14
  35. #define SendDataResponseType    4014
  36. #define SendLocalRequestType    15
  37. #define SendLocalResponseType    4015
  38.  
  39. /* error response codes */
  40. #define noError                0
  41. #define badMessageType        1
  42. #define badRequestLength    2
  43. #define unimplementedErr    3
  44.  
  45. /* response codes for connection status and open */
  46. #define openResPending        10        /* name resolution in progress */
  47. #define openResFailed        11        /* name resolution failed */
  48. #define    openConnPending        12        /* connection in progress */
  49. #define    openConnFailed        13        /* connection failed */
  50. #define openNegOptions        14        /* option negotiation in progress */
  51. #define    openLineMode        15        /* connection opened in line mode */
  52. #define open3270Mode        16        /* connection opened in 3270 mode */
  53. #define openNoSessions        17        /* no more sessions available */
  54. #define openFormatErr        18        /* invalid screen format specified */
  55. #define openBadId            19        /* (status) no conn. record for msgid */
  56. #define openNoMemory        20        /* memory not available for new connection */
  57.  
  58. /* response codes for close notification request */
  59. #define closeNotifyActive    30        /* close notification already active */
  60.  
  61. /* close event codes */
  62. #define closeNetFail        31        /* network failure */
  63. #define closeNetClose        32        /* network connection closed */
  64. #define closeAPI            33        /* API request */
  65. #define closeUser            34        /* user action */
  66. #define closeUnknown        35        /* undetermined */
  67.  
  68. /* response codes for write notification request */
  69. #define writeNotifyActive    40        /* write notification already active */
  70.  
  71. /* response codes for send data and send local request */
  72. #define sendLocked            50        /* send rejected- keyboard is locked */
  73. #define sendBadAddress        51        /* cursor address is invalid */
  74. #define sendInsErr            52        /* no room for char. in insert mode */
  75. #define sendAttrErr            53        /* attempt to overwrite attr. byte */
  76. #define sendProtErr            54        /* attempt to store in protected field */
  77. #define sendAIDErr            55        /* invalid AID code specified */
  78. #define sendFmtErr            56        /* invalid for unformatted screen */
  79. #define sendOpErr            57        /* invalid op code for send local */
  80.  
  81. /* API calls for the Session Manager */
  82.  
  83. /* The session manager is called to create new sessions.  Once a
  84.    session is created, all subsequent API calls are made to the
  85.    session itself.  For SPPC, the session manager registers itself
  86.    as "GFTMn", where "n" is a digit from 1 through 8.  For PPC,
  87.    the session manger registers itself as "tn3270 #n".  This form
  88.    of registration allows multiple copies of tn3270 to be running
  89.    at the same time.  "n" will be the lowest number not already
  90.    in use at the time tn3270 is launched.                        */
  91.    
  92. /* Session Manager: Error Response
  93.    If the session manager receives a message type it cannot
  94.    identify, or a request which cannot be executed for some
  95.    reason, it returns an error response structure:                */
  96.  
  97. typedef struct {
  98.     short msgtype;            /* ErrorResponseType */
  99.     short code;                /* error code */
  100.     } ErrorResponse;
  101.  
  102. /* Session Manager: Get Id
  103.    This call returns the signature, name, and reference number of the
  104.    tn3270 application.  The name allows the API client to identify the
  105.    application by the same name the user has assigned to it.                            */
  106.    
  107. typedef struct {
  108.      short    msgtype;            /* GetIdRequestType */
  109.     } GetIdRequest;
  110.     
  111. typedef struct {
  112.     short    msgtype;            /* GetIdResponseType */
  113.     OSType    signature;            /* 4-character application signature */
  114.                                 /* "GFTM" for standard tn3270 */
  115.     short     refnum;                /* app. resource file refnum */        
  116.     unsigned char appname[120];    /* application file name */
  117.     } GetIdResponse;
  118.  
  119. /* Session Manager: GetCapabilities
  120.    This call returns information describing the valid parameters
  121.    for creating new sessions.  The client sends a GetCapRequest
  122.    structure, and the API returns a GetCapResponse structure:    */
  123.    
  124. typedef struct {
  125.      short    msgtype;        /* GetCapRequestType */
  126.     } GetCapRequest;
  127.     
  128. typedef struct {
  129.     short ptsize;            /* point size */
  130.     short rows;                /* number of rows */
  131.     short cols;                /* number of columns */
  132.     } screenformat;
  133.  
  134. typedef struct {
  135.     short    msgtype;        /* GetCapResponseType */
  136.     short    pendsessions;    /* current number of pending sessions */
  137.     short    currsessions;    /* current number of opened sessions */
  138.     short    maxsessions;    /* maximum number of sessions */
  139.     short    numbformats;    /* number of screen formats which follow */ 
  140.     screenformat sizeinfo[2];    /* max. dimensions for each pointsize */
  141.     } GetCapResponse;
  142.  
  143. /* Session Manager: GetVersion
  144.    This call returns the contents of tn3270's 'vers' 1 resource.  The
  145.    client sends a GetVersRequest structure, and the API returns a
  146.    GetVersResponse structure.  If the 'vers' 1 resource is not available
  147.    for some reason, the "verssize" field of the response will be set
  148.    to zero.                                                                */
  149.    
  150. typedef struct {
  151.      short msgtype;                    /* GetVersRequestType */
  152.     } GetVersRequest;
  153.  
  154. typedef struct {
  155.     short msgtype;                    /* GetVersResponseType */
  156.     short verssize;                    /* size of 'vers' 1 resource */
  157.     unsigned char versdata[120];    /* contents of 'vers' 1 resource 
  158.                                        (actual size given by "verssize") */
  159.     } GetVersResponse;
  160.     
  161. /* Session Manager: OpenSession
  162.    This call creates a new session according to the parameters in
  163.    the OpenRequest structure.  The session manager returns an
  164.    OpenResponse structure when the open suceeds, or has failed for
  165.    some reason.    Due to network conditions, it may take as long as
  166.    several minutes before a response is generated.
  167.    Storage for the hostname and windowname strings may be released
  168.    once the OpenResponse is received.                                 */
  169.    
  170. typedef struct {
  171.     short msgtype;                /* OpenRequestType */
  172.     unsigned char *hostname;    /* host name to connect to,
  173.                                    maximum length = 255      */
  174.     unsigned char *windowname;    /* name for new window,
  175.                                    maximum length = 255         */
  176.     screenformat dfltsize;        /* default screen size (24 by 80) */
  177.     screenformat altsize;        /* alternate screen size */
  178.     char hide;                    /* true if window should be hidden */
  179.     char nowsf;                    /* true to suppress WSF support */
  180.     char noalert;                /* true to suppress alerts to user */
  181.     } OpenRequest;
  182.  
  183. typedef struct {
  184.     short msgtype;                /* OpenResponseType */
  185.     short code;                    /* error code (or noError) for open */
  186.     short sppcrefnum;            /* SPPC refnum for new session */
  187.     short ppcportnum;            /* PPC portRefNum for new session */
  188.     unsigned char sppcname[9];    /* SPPC name for new session */
  189.     unsigned char ppcname[21];    /* PPC name for new session */
  190.     } OpenResponse;
  191.  
  192. /* Session Manager: GetConnectionStatus
  193.     This call returns the status of a pending connection.  A
  194.     connection is pending when an open request has been made for
  195.     the connection, but an open response has not been generated
  196.     yet.                                                          */
  197.    
  198. typedef struct {
  199.     short msgtype;                /* GetConnStatusType */
  200.     unsigned long openid;        /* message id of session open request */
  201.     } GetConnStatus;
  202.  
  203. typedef struct {
  204.     short msgtype;                /* GetConnResponseType */
  205.     unsigned long openid;        /* openid from GetConnStatus */
  206.     short statuscode;            /* code for connection status */
  207.     } GetConnResponse;
  208.  
  209. /* API Calls for Sessions */
  210.  
  211. /* For SPPC, each session registers itself as "GFTMn-i", where
  212.    "GFTMn" is the same as the session manager registration, and
  213.    "i" is a digit from 1 through 8.  For PPC, each session registers
  214.    itself as "tn3270 #n session i".  "i" will be the lowest number
  215.    not already in use at the time the session is created.            */        
  216.    
  217. /* Sessions: Error Response
  218.    The error response for a session is the same as for the session
  219.    manager. (See above.)                
  220.                                                                    */
  221.                                                                 
  222. /* Sessions: GetCharacteristics
  223.    This call returns the characteristics of a session.  The client
  224.    sends a GetCharRequest message, and the API responds with a
  225.    GetCharResponse structure:                                    */
  226.  
  227. typedef struct {
  228.     short msgtype;                /* GetCharRequestType */
  229.     unsigned char *hostname;    /* pointer to storage for hostname */
  230.                                 /* must be 256 bytes (or more) */
  231.     unsigned char *windowname;    /* pointer to storage for windowname */
  232.                                 /* must be 128 bytes (or more) */
  233.     } GetCharRequest;
  234.     
  235. typedef struct {
  236.     short msgtype;                /* GetCharResponseType */
  237.     screenformat dfltsize;        /* default screen size (24 by 80) */
  238.     screenformat altsize;        /* alternate screen size */
  239.     char linemode;                /* true for a line mode session */
  240.     char hide;                    /* true if window is hidden */
  241.     char nowsf;                    /* true if WSF suppression was requested */
  242.     char noalert;                /* true if user alerts suppressed */
  243.     } GetCharResponse;
  244.  
  245. /* Sessions: Close
  246.    This calls requests that a session be closed.  The client sends
  247.    a CloseRequest structure, and the API responds with a CloseResponse
  248.    structure.                                                    
  249.    NOTE: tn3270 will not delay session close processing until the
  250.    response to the close request is read by the client.  Since session
  251.    close processing includes deregistering the session, when a close
  252.    is successful, in some cases the close response may never be
  253.    received.  However, this has never occurred during testing.    
  254.    */
  255.     
  256. typedef struct {
  257.     short msgtype;                /* CloseRequestType */
  258.     } CloseRequest;
  259.     
  260. typedef struct {
  261.     short msgtype;                /* CloseResponseType */
  262.     short code;                    /* error code (or noError) for close */
  263.     } CloseResponse;
  264.  
  265. /* Sessions: CloseNotification
  266.    This call allows a client to request notification when a session
  267.    closes.  Notification will occur when a session closes due to a
  268.    client's close request, and also when the session closes for other
  269.    reasons, such as a network problem, or action taken by the user.
  270.    The client sends a CloseNotifyRequest structure, and
  271.    receives a CloseNotifyResponse structure from the API.  In addition,
  272.    the client may, at some time in the future, receive a 
  273.    CloseEventResponse structure when the session closes.
  274.    Only one client may be defined to receive close notification for a
  275.    connection at any given time.
  276.    Notification may be reset at any time.  It is not an error to
  277.    reset notification when it has never been set.
  278.    NOTE: tn3270 will not delay session close processing until the
  279.    close notification is read by the client.  Since session
  280.    close processing includes deregistering the session, when a close
  281.    is successful, in some cases the close notification may never be
  282.    received.  However, this has never occurred during testing.         */   
  283.  
  284. typedef struct {
  285.     short msgtype;                /* CloseNotifyRequestType */
  286.     char notifyflag;            /* true to set, false to reset notify */
  287.     } CloseNotifyRequest;
  288.  
  289. typedef struct {    
  290.     short msgtype;                /* CloseNotifyResponseType */
  291.     short code;                    /* error code (or noError) for request */
  292.     } CloseNotifyResponse;
  293.  
  294. typedef struct {
  295.     short msgtype;                /* CloseEventResponseType */
  296.     short sppcrefnum;            /* SPPC refnum for connection */
  297.     short ppcportnum;            /* PPC portRefNum for connection */
  298.     short code;                    /* error code for cause of close */
  299.     } CloseEventResponse;
  300.  
  301.  
  302. /* Sessions: GetBuffers
  303.    This call allows a client to obtain the addresses of tn3270's
  304.    data and attribute buffers.  The addresses of the internal 
  305.    variables "kblock" and "kblcode" are returned, which indicate
  306.    whether and why the keyboard is locked.  Also, the address of
  307.    the internal variable "curadr" is returned, which contains the
  308.    cursor position.
  309.    
  310.    NOTE: The buffer addresses are provided to allow efficient
  311.          examination of the buffers.  This call is not intended to
  312.          allow the client to modify the buffers or variables, and
  313.          any such use is unsupported.  The effect of modifying
  314.          these data structures is unpredictable, and may change
  315.          in different versions of tn3270.  Use SendDataRequest
  316.          described below to update the buffers.
  317.    
  318.    The data buffer contains the data received in 3270 data streams,
  319.    and consists of one byte for each character position. 
  320.    The data is EBCDIC as received from the host, without being
  321.    translated.  X'1D' is stored in buffer positions corresponding
  322.    to field attributes (created by either the Start Field or
  323.    Start Field Extended orders).  However, the most reliable way
  324.    to test for a field attribute is to examine bit 15 of the
  325.    attribute bits (see below).
  326.    
  327.    The attribute buffer contains attribute information for each
  328.    data character, and consists of 16 bits for each character
  329.    position.  The bits are defined as follows (bit 15 is the most
  330.    significant bit):
  331.    
  332.    bit 15:        0 = data at this screen position
  333.                    1 = attribute byte at this screen position
  334.    bit 14:        0 = GE does not apply to this character
  335.                    1 = GE does apply to this character
  336.    bits 13-8:     For field attributes, these are the bits 5-0 (the
  337.                    least significant 6 bits) of the field attribute.
  338.    bits 7-6:    Character set for the character or field.  00 is the
  339.                    default character set; 01 is the APL/Text character
  340.                 set.  Other values are currently undefined, and
  341.                 map to the default character set.
  342.    bit 5:        Selection bit: set if this character is included
  343.                    in text selection (as done with the mouse).
  344.    bits 4-3:    Extended highlighting:
  345.                        00 = none
  346.                     01 = blink
  347.                     10 = reverse
  348.                     11 = underscore
  349.    bits 2-0:    Color:
  350.                        000 = default (green)
  351.                     001 = blue
  352.                     010 = red
  353.                     011 = pink
  354.                     100 = green
  355.                     101 = turquoise
  356.                     110 = yellow
  357.                     111 = white
  358.     
  359.     "kblock" is a single byte which is 0 when the keyboard is
  360.     unlocked, and 1 when the keyboard is locked.
  361.  
  362.     "kblcode" is a single byte with the following definition:
  363.         0 = keyboard is unlocked
  364.         1 = keyboard is locked: last write from host did not
  365.             unlock the keyboard
  366.         2 = keyboard is locked: waiting for host to respond
  367.             to last read response transmitted
  368.         3 = keyboard is locked due to communications error
  369.         4 = keyboard is locked due to no active session (should
  370.             not happen during API use)
  371.             
  372.     "curadr" is the screen offset of the cursor.  It is a 16-bit
  373.     unsigned integer.
  374.                                                                 */
  375.                                                                 
  376. typedef struct {
  377.     short msgtype;                /* GetBuffersRequestType */
  378.     } GetBuffersRequest;
  379.     
  380. typedef struct {
  381.     short msgtype;                /* GetBuffersResponseType */
  382.     unsigned char *databuff;    /* data buffer pointer */
  383.     unsigned short *attrbuff;    /* attribute buffer pointer */
  384.     unsigned char *kblock;        /* address of "kblock" */
  385.     unsigned char *kblcode;        /* address of "kblcode" */
  386.     unsigned short *curadr;        /* address of "curadr" */
  387.     } GetBuffersResponse;
  388.     
  389. /* Sessions: WriteNotification
  390.    This call allows the client to request notification of changes
  391.    to the data and attribute buffers.  Notification will occur
  392.    when any changes to the buffer contents are made due to write
  393.    commands received from the host.  Notification will also occur
  394.    when the host issues a read command.  Notification will not occur
  395.    when changes are made due to API or user-entered screen updates.
  396.    Only one client may be defined to receive write notification for
  397.    a connection at any given time.                                */
  398.    
  399. typedef struct {
  400.     short msgtype;                /* WriteNotifyRequestType */
  401.     char notifyflag;            /* true to set, false to reset notify */
  402.     } WriteNotifyRequest;
  403.     
  404. typedef struct {
  405.     short msgtype;                /* WriteNotifyResponseType */
  406.     short code;                    /* error code (or noError) for request */
  407.     } WriteNotifyResponse;
  408.     
  409. typedef struct {
  410.     short msgtype;                /* WriteEventResponseType */
  411.     short sppcrefnum;            /* SPPC refnum for connection */
  412.     short ppcportnum;            /* PPC portRefNum for connection */
  413.     unsigned char ccwop;        /* CCW op-code for this operation */
  414.                                 /* or 0 for line mode write */
  415.     } WriteEventResponse;
  416.  
  417.  
  418. /* Sessions: SendData
  419.    SendData allows the client to do any of the following, in order:
  420.            (1) set the current cursor address
  421.         (2) modify the data and attribute buffers
  422.         (3) send screen modifications to the host, with a specified
  423.              AID code.  An appropriate data stream for the given AID
  424.             code will be generated.                                
  425.     Data will be entered into the data buffer exactly as specified
  426.     in the data field, starting at the cursor address.  The cursor
  427.     address will then be updated following the same rules as for
  428.     user input.  Graphics Escape (GE) may be specified for a character
  429.     by preceding it by GE (X'08') in the data.  GE will never be stored
  430.     in the buffer, and is not included in the returned count of stored
  431.     characters.  
  432.     If the keyboard is locked, all three operations will be skipped,
  433.     and the response code "sendLocked" will be returned.        
  434.     If the cursor address is invalid, all three operations will be
  435.     skipped, and the response code "sendBadAddress" will be returned.
  436.     If a data character cannot be stored, the "code" field of the
  437.     response will indicate the type of error, and the "count" field
  438.     will contain the number of characters successfully stored.  Also,
  439.     any AID code specified will not be transmitted.
  440.     If an invalid AID code is specified, no AID code will be sent,
  441.     and the "code" field of the response will contain an error code.
  442.     For line mode sessions, steps 1 and 3 are skipped, and the data
  443.     consists of ASCII characters to be sent to the host.  In this case,
  444.     no errors are returned.                                            */
  445.     
  446. typedef struct {
  447.     short msgtype;                /* SendDataRequestType */
  448.     unsigned short curadr;        /* cursor address (screen offset),
  449.                                    or 65535 (-1) to leave unchanged */
  450.     unsigned char aidcode;        /* AID code to send, or 0 to skip */
  451.     unsigned char spare;        /* unused- set to 0 */
  452.     short length;                /* length of data to store, or 0
  453.                                     to skip    */
  454.     unsigned char data[120];    /* data to store */
  455.     } SendDataRequest;
  456.     
  457. typedef struct {
  458.     short msgtype;                /* SendDataResponseType */
  459.     short code;                    /* response code (or noError) */
  460.     short count;                /* number of characters stored */
  461.     unsigned short curadr;        /* ending cursor address */
  462.     } SendDataResponse;
  463.  
  464.  
  465. /* Sessions: SendLocal allows the client to perform a local terminal
  466.    operation.  A sequence of operation codes is sent in the data
  467.    field of the request.  If the keyboard is locked, SendLocal will
  468.    be rejected with the response code "sendLocked".  However, an
  469.    exception is that "reset" as the first local operation specified
  470.    will unlock the keyboard.  If an operation produces an error,
  471.    subsequent operations will not be performed.  The "code" field
  472.    in the response will indicated the type of error, and the "count"
  473.    field will indicate the number of completed operations.
  474.  
  475.    The operation codes are:
  476.            1    cursor up
  477.         2    cursor down
  478.         3    cursor left
  479.         4    cursor right
  480.         5    tab
  481.         6    backtab
  482.         7    newline
  483.         8    home
  484.         9    erase eof
  485.         10    erase input
  486.         11    toggle insert mode
  487.         12  delete character
  488.         13    reset keyboard
  489.         14    dup
  490.         15    field mark
  491.         16    toggle APL mode
  492.         17    insert blank
  493.         18    rubout
  494.         19    cursor up twice
  495.         20    cursor down twice
  496.         21    cursor left twice
  497.         22    cursor right twice
  498.         23    toggle cursor position display
  499.                                                                 */        
  500.    
  501. typedef struct {
  502.     short msgtype;                /* SendLocalRequestType */
  503.     short length;                /* length of data field */
  504.     long spare;                    /* unused- set to zero */
  505.     unsigned char data[120];    /* list of operation codes */
  506.     } SendLocalRequest;
  507.     
  508. typedef struct {
  509.     short msgtype;                /* SendLocalResponseType */
  510.     short code;                    /* response code (or noError) */
  511.     short count;                /* count of op codes executed */
  512.     unsigned short curadr;        /* ending cursor address */
  513.     } SendLocalResponse;
  514.